HTTP API

 

Zur Verwendung der HTTP API benötigen Sie zunächst einen Systembenutzer, der über die Berechtigung zur Nutzung der API verfügt.

 

 

ê Wir empfehlen dafür nicht den Benutzer "admin" zu verwenden, sondern einen neuen Benutzer mit eingeschränkten Berechtigungen zu erstellen.

 

 

 

1. Anlegen eines neuen Systembenutzers

 

  1. Melden Sie sich mit dem Benutzer admin am SMS Gateway an.
  2. Navigieren Sie über Konfiguration in der Menüleiste zum Punkt Systembenutzer.
  3. Erstellen Sie einen neuen Benutzer, z.B.: apiuser.
  4. Verwalten Sie die Berechtigungen des Benutzers über das Stift Symbol am Ende der Zeile.
    Erteilen Sie die Berechtigung Zugriff auf die HTTP API.
    Weitere Berechtigungen werden nicht benötigt.

 

 

2. Verwendung der HTTP API

 

Die API kann über die folgenden Adresse angesprochen werden: https://<SMS Gateway IP>/api.php.

 

An diese Schnittstelle können Sie via POST oder GET Daten übergeben.

 

 

Notwendig

 

Option Beschreibung
username Systembenutzer, der die Berechtigung zum Zugriff auf die HTTP API besitzt.
password Das Passwort des Benutzers.
text Inhalt der SMS.
to Empfänger der SMS, abhängig von mode.

 

 

Optional

 

Option Beschreibung
hexmode Mit true kann der Text in Hexadezimalem Format an die API übergeben werden. Standard ist false.
list Mit white wird eine Whitelist definiert, mit black wird eine Blacklist definiert. Benötigt den zusätzlichen Parameter regex.
mode

Modus, entspricht der nachfolgenden Tabelle. Bei ungültigem Modus wird die Nachricht mittels number versendet.

 

Option Bedeutung to Beschreibung
group

to = ID

(empfohlen) oder Name einer Benutzergruppe

 Mit dieser Option können sie eine SMS an eine Benutzergruppe versenden. Benutzergruppen werden über Konfiguration - Gruppen verwaltet. Die Verwendung von Gruppen erfordert die Lizenzierung des Moduls Empfängergruppen.
number to = Telefonnummer des Empfängers Mit dieser Option können Sie eine SMS an eine einzelne Telefonnummer versenden (Standard).
telgroup to = ID (empfohlen) oder Name einer Benutzergruppe Mit dieser Option können sie eine Nachricht mittels Automatik an eine Benutzergruppe versenden. Bei Automatik wird zunächst versucht die Benachrichtigung per Telegram zu versenden, schlägt dies fehl wird per SMS benachrichtigt. Benutzergruppen werden über Konfiguration - Gruppen verwaltet. Die Verwendung von Gruppen erfordert die Lizenzierung des Moduls Empfängergruppen.
telnumber to = Telefonnummer des Empfängers Mit dieser Option können Sie eine Nachricht mittels Automatik an eine einzelne Telefonnummer versenden. Bei Automatik wird zunächst versucht die Benachrichtigung per Telegram zu versenden, schlägt dies fehl wird per SMS benachrichtigt.
teluser to = ID (empfohlen) oder Name eines Kontakts aus dem Adressbuch Mit dieser Option können sie eine Nachricht mittels Automatik an einen Kontakt senden. Bei Automatik wird zunächst versucht die Benachrichtigung per Telegram zu versenden, schlägt dies fehl wird per SMS benachrichtigt. Kontakte werden über Konfiguration - Adressbuch verwaltet.
user to = ID (empfohlen) oder Name eines Kontakts aus dem Adressbuch Mit dieser Option können sie eine SMS an einen Kontakt senden. Kontakte werden über Konfiguration - Adressbuch verwaltet.
regex Hier kann eine Regular Expression übergeben werden. Falls diese auf die verwendet Absendernummer zutreffen sollte, wird mit list definiert ob die Absendernummer abgelehnt oder akzeptiert wird. Bitte beachten Sie eine möglicherweise notwendige URL-Enkodierung.
telauto

Mit false kann die Automatik-Option abgeschaltet werden. Wenn dies nicht deaktiviert ist, wird die Nachricht per SMS gesendet, wenn die Nummer des Empfängers nicht für Telegram verwendet wurde.
ring Durch Hinzufügen des Parameters “ring” wird ein Voice-Anruf ausgelöst. Der in “text” angegebene Text wird in diesem Fall ignoriert und nicht ausgewertet.
flash Der Parameter Flash erzeugt eine “Flash” Message (SMS Class 0), die in der Regel direkt auf dem Smartphone des Empfängers angezeigt wird.

 

 

ê Die Funktionen “Ring“ und “Flash SMS“ sind nur mit neueren Versionen (ab Kaufdatum 2021) des SMS Gateway nutzbar. Mit einer SIM-Karte, bei welcher nur das Versenden von SMS beinhaltet, funktioniert unsere “Ring“-Funktion nicht!

 

 

 

 

ê Es ist eine Lizenzierung für das Modul Telegram erforderlich. Diese Lizenzierung ist für Supportkunden kostenlos. Bitte wenden Sie sich an sales@brevis.one.

 

 

 

 

3. Fehlerrückgabe

HTTP Status Code Fehlerausgabe Beschreibung
400 Error. See Gateway logs for more information. Falscher Modus ausgewählt, Gruppe nicht vorhanden, Kontakt nicht vorhanden, Fehlerhafte Nummer.
400 Error: Parameter miss. Fehlende Parameter.
401 401 Unauthorized - Username or Password wrong. Username und/oder Passwort falsch eingegeben.
403 403 Forbidden - Your User has no right to send SMS over API. Der Benutzer hat keine Berechtigung SMS über die API zu versenden.
408 FAILED - Timeout or see Gateway logs for more information. Der Server hat das Zeitlimit überschritten und auf Anforderungen gewartet.

 

 

i Die Fehlercodes werden zusätzlich als HTTP-Response-Code ausgegeben.

 

 

 

4. Beispiele mit GET

 

4.1 Beispiel SMS

 

curl

 

 

curl -X GET "https://<IP SMS Gateway>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=number"

 

 

powershell

 

 

Invoke-WebRequest -Uri "https://<IP SMS Gateway>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=number" -Method GET

 

 

 

4.2 Beispiel Telegram

 

curl

 

 

curl -X GET "https://<IP SMS Gateway>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=telnumber&telauto=false"

 

 

powershell

 

 

Invoke-WebRequest -Uri "https://<IP SMS Gateway>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=telnumber&telauto=false" -Method GET

 

 

 

4.3. Beispiel Hexmode

 

curl

 

 

curl -X GET "https://<IP SMS Gateway>/api.php?text=48616c6c6f2064696573206973742065696e65205465737420534d53&to=00491701234567&username=apiuser&password=secret&hexmode=true"

 

 

powershell

 

 

Invoke-WebRequest -Uri "https://<IP SMS Gateway>/api.php?text=48616c6c6f2064696573206973742065696e65205465737420534d53&to=00491701234567&username=apiuser&password=secret&hexmode=true" -Method GET

 

 

 

5. Beispiele mit POST

 

5.1. Beispiel SMS

 

curl

 

 

curl -X POST -d "text=Test&to=00491701234567&username=apiuser&password=secret&mode=number" "https://<IP SMS Gateway>/api.php"

 

 

powershell

 

 

Invoke-WebRequest -Uri https://<IP SMS Gateway>/api.php -Method POST -Body @{username='apiuser';password='secret';to='01701234567';text='Test';mode='number'}

 

 

 

5.2. Beispiel Telegram

 

curl

 

 

curl -X POST -d "text=Test&to=00491701234567&username=apiuser&password=secret&mode=telnumber&telauto=false" "https://<IP SMS Gateway>/api.php"

 

 

powershell

 

 

Invoke-WebRequest -Uri https://<IP SMS Gateway>/api.php -Method POST -Body @{username='apiuser';password='secret';to='01701234567';text='Test';mode='telnumber';telauto='false'}

 

 

 

5.3. Beispiel Hexmode

 

curl

 

 

curl -X POST -d "text=48616c6c6f2064696573206973742065696e65205465737420534d53&to=00491701234567&username=apiuser&password=secret&hexmode=true" "https://<IP SMS Gateway>/api.php"

 

 

powershell

 

 

Invoke-WebRequest -Uri https://<IP SMS Gateway>/api.php -Method POST -Body @{username='apiuser';password='secret';to='01701234567';text='48616c6c6f2064696573206973742065696e65205465737420534d53';hexmode='true'}

 

 

 

 

❕ URL encoding

 

Einige Sonderzeichen und Leerzeichen können ohne URL-Encoding nicht über die HTTP API versendet werden. Verwenden Sie die Prozentdarstellung, um den Inhalt Ihrer Nachricht zu kodieren.

 

 

 

 

 

Verwandte Artikel